Light ROM 2/LIGHT-ROM 2 (Amiga Library Services)(1995).iso/programs/amiga/misc/clouds/clouds.txt

Text File | 1995-03-23 | 15KB | 415 lines

Copyright
---------

Clouds v1.01 software and documentation are copyright 1995 Krzysztof Kobus.
All Rights Reserved.



Disclaimer
----------

No responsibility or liability will be accepted for any damage that may
appear to have resulted from use of this program.  All use is at your own
risk.  The software is provided "as is" without any warranty implied or
otherwise to the fitness or accuracy of the software and documentation.
The author reserves the right to update the software and/or documentation
without notice.



The Program
-----------

1. Overview.

"Clouds" is the first program on Amiga platform, giving you visual
modeling and realistic animation of turbulent motion of clouds.  It is
based on spectral synthesis method.  The method employs a variety of
intuitive parameters describing natural properties of clouds phenomena, as
cloudiness, contrast, wind direction, strength of wind and turbulent
changes.  Such wide range of controls allows a creative animator to
generate all kinds of clouds, gases, mists and so forth.  Resulting images
can then be used as backgrounds, textures in 3-D programs or alpha channel
information - to mention just a few possibilities.  The program has
standardized user interface and is fully controlled via ARexx.  "Clouds" is
Kickstart 1.3/2.0/3.0 compatible although its all possibilities can be
achieved only under 2.0+.  Additionally, program takes advantage of AGA
chipset.


2. Getting started.

  2.1 Size of the image.

Spectral synthesis, which the entire idea is based on, requires Fourier
Transformation calculations to be made.  In order not to calculate single
frame by several hours, Fast Fourier Transform (FFT) has been implemented
in the program, what apart from major speed up, gave rise to some
restrictions concerning picture size.  With FFT, only square regions can be
calculated and then their width must be equal to natural power of two (16,
32, 64, 128, 256, 512, 1024 in this case).

To get rid of this limitation "Clouds" is equipped with Goraud scaling
engine, and is able to produce smooth images of any size supported by IFF
picture format.  Yet, it shouldn't be forgotten that original picture is
always a square, which side's length is equal to FFT parameter, thus this
is the parameter of the highest importance for detail's level of the final
picture.  Its value can be changed by pressing cycle gadget with FFT on it,
located in the bottom part of the main screen.  Size of the output picture
can be defined by typing needed values in "Width" and "Height" gadgets.

In the further part of this manual the original picture will be referred
to as "texture", and the final picture, defined by "Height" and "Width"
simply as "the picture" or "the image".

  2.2 The "Control" parameter.

The state of "Control" gadget determines what happens to calculated
images.  Actually there are three possibilities:

  - Only Save    : Pictures go only to the disk.
  - Only Display : Pictures are displayed on the screen which opens
                   especially for this purpose.
  - Display&Save : This is the combination of above two.


  2.3 Opening the project.

When image and texture size have been set and gadget "Control" is in
required position, one can attempt to open the project.  It should be
stated here that as "the project" we mean not only animation, but single
pictures as well.  To accomplish this please select "Project/Open project"
from  the  menu.   What  happens  now  depends mostly on text that reads on
the "Control" gadget:

  - Only Save.  The file requester appears asking you to specify path and
root filename for storing image data.  This means that should select volume
and drawer where you want images to be written and then type the name that
is "base name" and which will be appended with frame number (according to
"Config/Save format" option - see 6.2.3) when saved.  Quickly after that,
program starts to allocate memory required for calculations.  In case of
failure, message "Sorry, not enough memory..." appears.  If so, you should
decrease parameter FFT, as its value is strongly related to amount of used
memory (the higher value the more RAM you need) and then try again to
select "Project/Open project".

  - Only Display. Programs immediately starts to allocate needed memory,
and short after that tries to open screen for graphical visualization of
the calculations (this means you will see the clouds on it). If any
problems occur, message "Cannot open graphics environment..." is displayed
on the screen. Usually, this happens as the result of insufficient memory.

  - Display&Save. Actions taken will be combination of above two.

If everything went right gadget "Calculate" becomes unghosted and
"Control", "FFT", "Width", "Height" and "Quit" gadgets - ghosted (i.e. you
can't change them).


3. Parameters.

Having the project successfully opened one can proceed with settings
describing directly cloud's appearance and controlling animation system.

  3.1 Spatial structure parameters.

    3.1.1 Seed.
          This is the start value for random number generator. By changing
          this value you can obtain different shapes of basic cloud's
          structure.

    3.1.2 Roughness.
          As the name indicates describes roughness level of cloud.
          The smaller values the stronger level of roughness and vice versa.

    3.1.3 Granularity.
          By increasing this parameter, "water-color" effect can be
          achieved and clouds appear to be some more "delicate".

  3.2 Turbulence parameters.

    3.2.1 Globality.
          Observations conducted in the past show that during real motion
          of clouds (and other gases) turbulent changes happen in the very
          first row to smallest eddies.  All in all it wasn't so hard to
          notice that on cloudy and windy day, when clouds move across the
          sky, large structures are nearly unmodified and these are small
          ones that undergo changes.  The "Globality" parameter is expressed
          in percents and specifies how big structures are to be modified
          in turbulent way (e.g.  5 percent means only very small ones, 100
          percent - all of the structures).

    3.2.2 Strength.
          Determines speed of turbulent changes measured in pixels of
          texture per frame.

    3.2.3 Abruptness.
          Small values of this parameter additionally strengthen movement of
          large structures. Big ones - decrease.

  3.3 Wind parameters.

    3.3.1 Velocity.
          Defines speed of translative changes. It is measured in pixels
          per  frame  and this value corresponds to the texture, not to the
          image  defined  by "Width", and "Height" parameters.  For example
          if you specify "FFT" equal to 128, Width = 256, Height = 256 and
          Velocity equal to 1.00, then resulting speed on the image,
          measured in pixels per frame will be equal to 2.00.

    3.3.2 Direction.
          This parameter indicates direction of translative motion. It is
          measured in degrees. This parameter also corresponds to texture.

  3.4 Cloud parameters.

    3.4.1 Density.
          Specifies white to blue ratio. The higher value - the more white
          color in the image.

    3.4.2 Contrast.
          As the name indicates - specifies contrast of the resulting image.

4. Calculating

Just before you start producing your images, number of frames to be
generated should be specified in the "Frames" gadget.  It not necessarily
means that your finished animation will be of that length, because if you
want to change some cloud's properties in time, you should set this field
to some small value, calculate, then modify required properties (as density
or speed) and calculate again, possibly changing "frames" to new value.
This will result in length of your animation being a sum of specified frame
values.  To easily achieve interesting results we advise you to use ARexx,
which greatly simplifies the process.

Depressing "Calculate" gadget starts the calculation procedure.  The
first frame may take longer to compute as some precalculations have to be
made.



5. Menus.

  5.1 Project

    5.1.1 Open Project.
          Opens project, possibly asking you for path/filename and/or
          opening the screen for graphics output.

    5.1.2 Close Project.
          Closes project, frees memory and closes rendering screen if it
          was present.

    5.1.3 About.
          Displays some information about "Clouds'" author and
          ARexx's port name.

    5.1.4 Quit.
          Ends session with "Clouds".


  5.2 Config

    5.2.1 Display colors.
          This allows you choose how many colors will be present in images
          rendered by "Clouds".  The option allows for 16 or 256 color
          screen.  The 256-colors rendering is only available on AGA machines.

    5.2.2 Save colors.
          This options selects how many colors will be present in frames
          saved to disk. This time the 256-colors are accessible for all
          Amigas, moreover - it is recommended.

    5.2.3 Save format.
          Specifies format of filenames used for saving frames.

    5.2.4 Priority.
          Specifies program's task priority while calculating.

    5.2.5 Screen mode.
          This option is available only under System 2.1+. It allows you
          specify display screen's mode.

    5.2.6 Load config.
          Can be used to load configuration files other than
          "clouds.config", which is loaded automatically. File requester
          which will appear should be used to select file previously saved
          with the "Save config" option.

    5.2.7 Save config.
          Saves actual settings of config menu, and state of all
          other parameters including "Control" and "FFT". File
          requester will appear allowing you to specify configs' file name.
          When "Clouds" is invoked, it automatically looks for "clouds.config"
          file in the actual directory, to use it as a default config.



ARexx
-----

"Clouds" features a full ARexx interface. All functions can be
controlled from ARexx, and there are even some additional commands
accessible only from ARexx. There is a brief description of all
available commands. Parameters given in "{}" are required, while
parameters in "[]" are optional and may be omitted. Every command
returns 0 in RC if everything went right,  else it returns 10 in RC
and short note in CLOUDS.LASTERROR prompting why an error occurred.

Following ARexx commands have identical meaning as theirs GUI equivalents
described above:

  * cl_Seed           {n}
  * cl_Roughness      {n}
  * cl_Granularity    {n}
  * cl_Globality      {n}
  * cl_Strength       {n}
  * cl_Abruptness     {n}
  * cl_Velocity       {n}
  * cl_Direction      {n}
  * cl_Density        {n}
  * cl_Contrast       {n}

  * cl_Frames         {n}
  * cl_Width          {n}
  * cl_Height         {n}
  * cl_Fft            {16 | 32 | 64 | 128 | 256 | 512 | 1024}
  * cl_Control        {DisplayAndSave | OnlyDisplay | OnlySave}

  * cl_Quit
  * cl_About

  * cl_DisplayColors  {16 | 256}
  * cl_SaveColors     {16 | 256}

  * cl_ScreenMode
  * cl_Priority       {-1 | 0 | 1}
  * cl_SaveFormat     {%s%d | %s%03d | %s%04d | %s.%d | %s.%03d | %s.%04d}

  * cl_CloseProject

  * cl_OpenProject    [filename]

  * cl_LoadConfig     [filename]
  * cl_SaveConfig     [filename]

  * cl_Calculate
    This command can also return value 5 in RC. This case means that
    calculations have been cancelled by the user.

Following commands are accessible only from ARexx level:

  * cl_QuitNow
    Causes program to quit unconditionally. No questions asked.

  * cl_Information    {information}
    Brings up a text requester displaying short, one line long information.

  * cl_Question       {question}
    Brings up a text requester displaying short, one line long question.
    The user will have two possible answers: 'OK' and 'Cancel'. The command
    returns 5 in RC if 'OK' was pressed, otherwise RC is equal to 0.



Additional Notes
----------------

To run "Clouds v1.01" you need some libraries installed in your "LIBS:"
drawer. These are:
  - mathtrans.library
  - asl.library (V36+, preferably V38+) required only under Kick2.0+
  - req.library required under Kick1.3, not used under Kick2.0+
  - rexxsyslib.library, mathieeedoubbas.library required only if you
    want to take advantage of ARexx interface.



Acknowledgements
----------------

The author wishes to express his thanks to Georgios Sakas for development
of the method.



Distribution
------------

Clouds v1.01 is a shareware program.  You may freely distribute it as long
as all of its files are included in their original form without additions,
deletions, or modifications of any kind, and only a nominal fee is charged
for its distribution.  It cannot be distributed as a part of commercial
product without author's written permission.  If you like it and use it,
the author encourage you to register.  The shareware fee is USA $20 or 20
DM.  Registered users will be shipped a disk containing the latest release
version of Clouds and also version optimized for math coprocessor.  By
cooperating with this concept you help to ensure continued development of
this product.  Please send your registration card (Orderform) and money
(cash) to address below.

Thank you for supporting shareware.


Contact addresses
-----------------

e-mail: [e-mail]

Krzysztof Kobus
ul. Chopina 38/2
71-450 Szczecin
POLAND



Orderform
---------

For registration, send this form along with USA $20 or 20 DM to:
Krzysztof Kobus, ul. Chopina 38/2, 71-450 Szczecin, POLAND.


 **********************************************************************

      Krzsztof Kobus             *** **    ****  **  ** ****    ***
                                **   **   **  ** **  ** **  ** **
      ul. Chopina 38/2          **   **   **  ** **  ** **  **  ***
      71-450 Szczecin           **   **   **  ** **  ** **  **    **
      Poland                     *** ****  ****   ****  ****   ****

 **********************************************************************

      Name: _______________________________________________________

   Address: _______________________________________________________

      City: ___________________________ State: ____________________

        PC: ___________________________ Country: __________________

    E-Mail: _______________________________________________________

    Config: _______________________________________________________

   I use Clouds v ___.___ and love / hate the following things:

            _______________________________________________________

            _______________________________________________________

            _______________________________________________________

            _______________________________________________________

                                      __                __
          Shareware fee included:    (__) DM20,-   or  (__) $20,-
                       __
          I use MUI:  (__)

      I have read the Copyright and Distribution notes and do agree.


      Date: _____________________     Signature: __________________